home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE1 / EASYC / !EasyC++ / h / flex < prev    next >
Text File  |  1995-04-14  |  6KB  |  166 lines
  1. /****************************************************************************
  2.  * This source file was written by Acorn Computers Limited. It is part of   *
  3.  * the RISCOS library for writing applications in C for RISC OS. It may be  *
  4.  * used freely in the creation of programs for Archimedes. It should be     *
  5.  * used with Acorn's C Compiler Release 3 or later.                         *
  6.  *                                                                          *
  7.  ***************************************************************************/
  8.  
  9. /*
  10.  * Title  : flex.h
  11.  * Purpose: provide memory allocation for interactive programs requiring
  12.  *          large chunks of store. Such programs must respond to memory
  13.  *          full errors.
  14.  *
  15.  */
  16.  
  17. #ifndef __flex_h
  18. #define __flex_h
  19.  
  20. #ifdef __cplusplus 
  21. extern "C" {
  22. #endif
  23.  
  24. typedef void **flex_ptr;
  25.  
  26.  
  27. /* ----------------------------- flex_alloc -------------------------------
  28.  * Description:   Allocates n bytes of store, obtained from the Wimp.
  29.  *
  30.  * Parameters:    flex_ptr anchor -- to be used to access allocated store
  31.  *                int n -- number of bytes to be allocated
  32.  * Returns:       0 == failure, 1 == success
  33.  * Other Info:    You should pass the & of a pointer variable as the first
  34.  *                parameter. The allocated store MUST then be accessed
  35.  *                indirectly, through this, ie. (*anchor)[0] ..(*anchor)[n]
  36.  *                This is important since  the allocated store may later be
  37.  *                moved (it's a shifting heap!!). If there's not enough
  38.  *                store returns zero leaving anchor unchanged.
  39.  *
  40.  */
  41.  
  42. int flex_alloc(flex_ptr anchor, int n);
  43.  
  44.  
  45. /* ------------------------------ flex_free -------------------------------
  46.  * Description:   Frees the previously allocated store.
  47.  *
  48.  * Parameters:    flex_ptr anchor -- pointer to allocated store
  49.  * Returns:       void.
  50.  * Other Info:    *anchor will be set to 0.
  51.  *
  52.  */
  53.  
  54. void flex_free(flex_ptr anchor);
  55.  
  56.  
  57. /* ------------------------------- flex_size ------------------------------
  58.  * Description:   Informs caller of the number of bytes allocated
  59.  *
  60.  * Parameters:    flex_ptr -- pointer to allocated store
  61.  * Returns:       number of allocated bytes. 
  62.  * Other Info:    None.
  63.  *
  64.  */
  65.  
  66. int flex_size(flex_ptr);
  67.  
  68.  
  69. /* --------------------------- flex_extend --------------------------------
  70.  * Description:   Extend ot truncate the store area to have a new size.
  71.  *
  72.  * Parameters:    flex_ptr -- pointer to allocated store
  73.  *                int newsize -- new size of store
  74.  * Returns:       0 == failure, 1 == success.
  75.  * Other Info:    None.
  76.  *
  77.  */
  78.  
  79. int flex_extend(flex_ptr, int newsize);
  80.  
  81.  
  82. /* --------------------------- flex_midextend -----------------------------
  83.  * Description:   Extend or truncate store, at any point.
  84.  *
  85.  * Parameters:    flex_ptr -- pointer to allocated store
  86.  *                int at -- location within the allocated store
  87.  *                int by -- extent
  88.  * Returns:       0 == failure, 1 == success
  89.  * Other Info:    If by is +ve, then store is extended, and locations above
  90.  *                "at" are copied up by "by".
  91.  *                If by is -ve, then store is reduced, and any bytes beyond
  92.  *                "at" are copied down to "at"+"by".
  93.  *
  94.  */
  95.  
  96. int flex_midextend(flex_ptr, int at, int by);
  97.  
  98.  
  99. /* ---------------------------- flex_budge --------------------------------
  100.  * Description:    Function to move flex store, when the C library needs
  101.  *                 to extend the heap.
  102.  *
  103.  * Parameters:     int n -- number of bytes needed by C library
  104.  *                 void **a -- address of acquired store.  
  105.  * Returns:        amount of store acquired.
  106.  * Other Info:     Don't call this function directly, but register it 
  107.  *                 with the C library via:
  108.  *                    _kernel_register_slotextend(flex_budge);
  109.  *                 This will cause flex store to be moved up if the C
  110.  *                 library needs to extend the heap.  Note that in this 
  111.  *                 state, you can only rely on pointers into flex blocks 
  112.  *                 across function calls which do not extend the stack and 
  113.  *                 do not call malloc.
  114.  *                 The default state is flex_dont_budge, so, if required, 
  115.  *                 this function should be registered AFTER calling 
  116.  *                 flex_init().
  117.  *
  118.  */
  119.  
  120. extern int flex_budge(int n, void **a);
  121.  
  122.  
  123. /* -------------------------- flex_dont_budge -----------------------------
  124.  * Description:   Function to refuse to move flex store, when the C library 
  125.  *                needs to extend the heap.
  126.  *
  127.  * Parameters:    int n -- number of bytes needed by C library
  128.  *                void **a -- address of acquired store.
  129.  * Returns:       amount of store acquired (always 0).
  130.  * Other Info:    Don't call this function directly, but register it 
  131.  *                with the C library via:
  132.  *                   _kernel_register_slotextend(flex_dont_budge);
  133.  *                If the C library needs to extend the heap, flex will 
  134.  *                refuse to move. This means that you can rely on pointers 
  135.  *                into flex blocks across function calls.
  136.  *                This is the DEFAULT state after flex_init().
  137.  *
  138.  */
  139.  
  140. extern int flex_dont_budge(int n, void **a);
  141.  
  142.  
  143. /* ---------------------------- flex_init ---------------------------------
  144.  * Description:   Initialise store allocation module.
  145.  *
  146.  * Parameters:    void.
  147.  * Returns:       void.
  148.  * Other Info:    Must be called before any other functions in this module.
  149.  *
  150.  */
  151.  
  152. void flex_init(void);
  153.  
  154.  
  155. #ifdef __cplusplus
  156. }
  157. #endif
  158.  
  159.  
  160. #endif
  161.  
  162. /* end flex.h */
  163.  
  164.  
  165.  
  166.